跳到主要内容

Oauth2.0 API

Fanbook Developer

正式:https://a1.fanbook.cn/open/

Oauth2.0#

使用票证的授权方式#

Oauth 序列图02#

应用

 Generated

获取应用信息#

请求格式:

• Method:GET

• Path:/open/oauth2/app

Header 参数

参数名描述
authorizationFanbook 会话 token

Query 参数

参数名类型是否必须描述
client_idstring
redirect_urlstring授权后跳转的地址

返回数据:

参数名类型是否必须描述
appApplication应用信息
userUser授权用户信息

打开授权页面(**For Web**#

请求格式:

• Method:GET

• Path:/open/oauth2/authorize

Header 参数

参数名描述

Query 参数

参数名类型是否必须描述
response_typestring固定值:code
client_idstring
statestring自定义状态数据,传入的值会直接返回

返回数据:

参数名类型是否必须描述

确认授权#

请求格式:

• Method:POST

• Path:/open/oauth2/authorize

Header 参数

参数名描述
authorizationFanbook 会话 token

Query 参数

参数名类型是否必须描述
response_typestring固定值:code
client_idstring
allowbool授权行为,true: 允许,false: 拒绝
status_codestring自定义 response status code,默认返回 302,可选值:[200, 302]
statestring自定义状态数据,传入的值会直接返回,一般用于安全验证,前端可以验证服务器的返回是否一致,可以是用户session的hash值,或者是可以唯一标识会话的任意值。

返回数据:

参数名类型是否必须描述
locationstring重定向地址

换发 Token#

请求格式:

• Method:POST

• Path:/open/oauth2/token

Header 参数

参数名描述
content-typeapplication/x-www-form-urlencoded
authorizationBasic {base64_encode(client_id:client_secret)}

注意这里的content-type。另外authorization的生成,如果client_id为"123456",client_secret为"aSecret",那么authorization应为 "Basic MTIzNDU2OmFTZWNyZXQ="

Body 参数

参数名类型是否必须描述
grant_typestring固定值:authorization_code
codestring通过授权获得到 code,一次使用有效
redirect_uristring创建应用时预先设置的跳转地址

返回数据:

参数名类型是否必须描述
access_tokenstring
refresh_tokenstring
token_typestring固定值:bearer
expires_inint
scopeToken 适用的 scope

刷新 Token#

请求格式:

• Method:POST

• Path:/open/oauth2/refresh

Header 参数

参数名描述
content-typeapplication/x-www-form-urlencoded
authorizationBasic {base64_encode(client_id:client_secret)}

Body 参数

参数名类型是否必须描述
grant_typestring固定值:refresh_token
refresh_tokenstring
redirect_uristring-

返回数据:

参数名类型是否必须描述
access_tokenstring
refresh_tokenstring
token_typestring固定值:bearer
expires_inint
scopeToken 适用的 scope

使用implicit的授权方式#

时序图#

http://www.plantuml.com/plantuml/png/SoWkIImgAStDuN9pKj2rKtW-PSMpZkrM2i-wErzitVwih-FPtEQN2xToGSGLT85At9oi59utxNpQlllfX9vdBVrS8ArWyNZ7q10FAmNznDAIZFoYpAfKZVJK4aq5aBoDhYwIWgBKbCoYrEIIpFmy1MC38vZTQzOysT7vRDhEfxkc0EspUjdU-tJThASJ9Zxjs80cn-MGcfS2T3K0

 Generated

接口说明#

打开授权页面(**For Web**#

请求格式:

• Method:GET

• Path:/open/oauth2/authorize

Header 参数

参数名描述

Query 参数

参数名类型是否必须描述
response_typestring固定值:token
client_idstring
statestring自定义状态数据,传入的值会直接返回
redirect_uristring重定向地址,一定要跟申请应用时填写的重定向地址一致,否则会返回错误信息,授权失败
scopestring授权权限的枚举,多个权限值直接必须使用“%20” 连接,比如user.link%20user.info,下文有对权限的描述
status_codestring指定返回时使用的状态码,默认是返回302,可以指定为200,则会返回的body里带上location,即重定向后的地址

返回数据:

默认会在返回的header里包含了location字段,字段内容示例如下: http://localhost/#access_token=z7Aj7v/qN7T//uQq1ohquw==&token_type=Bearer&expires_in=3599&scope=user.link%20user.info&state=3

参数名类型是否必须描述
access_tokenstring返回的token信息
token_typestringtoken的类型,目前为固定值"Bearer"
expires_instring有效时间,默认为3600秒
scopestring授权权限的枚举,多个权限值直接必须使用“%20” 连接,比如user.link%20user.info
statestring自定义状态数据,返回请求里填充的state值

获取用户个人数据#

请求格式:

• Method:POST

• Path:/open/api/user/getMe

Header 参数

参数名描述
content-typeapplication/json
authorizationBearer {access_token}

JSON 参数

参数名类型是否必须描述

返回数据:

参数名类型是否必须描述
statusbool
dataUser
messagestring

获取个人服务器列表#

请求格式:

• Method:POST

• Path:/open/api/guild/getGuilds

Header 参数

参数名描述
content-typeapplication/json
authorizationBearer {access_token}

JSON 参数

参数名类型是否必须描述

返回数据:

参数名类型是否必须描述
statusbool
dataArray of Guild
messagestring

Open API Types#

User#

用户个人信息

字段类型是否必须描述
user_idstring用户全局唯一 ID
nicknamestring用户昵称
usernamestring用户可读标识 ID
avatarstring头像
tokenstring

Application#

应用信息

字段类型是否必须描述
client_idstring应用 ID
descriptionstring应用简介
iconstring应用 ICON 标识地址
namestring应用名称
scopesstring应用申请的权限范围

GuildCredit#

用户服务器荣誉数据

字段类型是否必须描述
authorityCreditAuthority荣誉颁发者
titleCreditTitle荣誉 title,展示在聊天会话中的个人头像右侧
slotsArray of CreditSlot array荣誉槽,展示在个人信息页,是二维数组

CreditAuthority#

服务器荣誉颁发者详情

字段类型是否必须描述
iconstring荣誉颁发者形象 logo url 地址
namestring荣誉颁发者名称

CreditTitle#

服务器荣誉 Title

字段类型是否必须描述
imgstring荣誉 Title 图形 url 地址

CreditSlot#

服务器荣誉槽

字段类型是否必须描述
labelstring是,与 img 二选一荣誉文本标题
imgstring是,与 label 二选一荣誉图形标题
valuestring荣誉值本值

Open API 签名方法#

权限定义#

权限描述
user.info用户的基本信息,用户nickname和avatar等等
user.link用户的电话号码